Summary

Ports the ComplexWatsonDistribution from MATLAB/libDirectional to Python.

Reference

Mardia, K. V. & Dryden, I. L., The Complex Watson Distribution and Shape Analysis, JRSS-B, 1999, 61, 913–926.

Changes

New file: pyrecest/distributions/hypersphere_subset/complex_watson_distribution.py

Implements ComplexWatsonDistribution – a distribution over the complex unit sphere C^D with pdf:

f(z) = C_D(κ) · exp(κ · |μᴴ z|²)

Methods:

• __init__(mu, kappa) – takes complex unit vector mu (shape (D,)) and scalar kappa
• mean() – returns mu
• pdf(za) – evaluates density at rows of complex array za (shape (N, D))
• sample(n) – samples n points on the complex unit sphere using the complex Bingham sampling algorithm (Mardia & Jupp 2009, p. 336)
• log_norm(D, kappa) – static; log normalization constant using three numerical regimes (low/medium/high κ) for stability across the full κ range
• fit(Z, weights=None) – classmethod; MLE fit
• estimate_parameters(Z, weights=None) – static; Mardia & Dryden MLE (scatter matrix eigendecomposition + hypergeometric ratio inversion)
• _hypergeometric_ratio_inverse(rho, D, kappa_max) – static; solves 1F1(2;D+1;κ) / (D · 1F1(1;D;κ)) = ρ using mpmath + scipy.optimize.brentq

Updated: pyrecets/distributions/__init__.py

• Imports and exports ComplexWatsonDistribution

New file: pyrecest/tests/distributions/test_complex_watson_distribution.py

20 unit tests covering: construction, mean(), log_norm(), pdf() (symmetry/phase-invariance/positivity), sample() (shape/unit-norm), and estimate_parameters()/fit().

Notes

• Uses numpy directly for complex arithmetic (no pyrecets backend abstraction needed since complex tensor support varies across backends)
• mpmath is used for the hypergeometric function evaluations to avoid float64 overflow for large κ